• Add pydantic DTOs for auth API request/response validation
• Split auth.py into auth/ package structure with handler and adapter
• Add compatibility tests verifying trafaret and pydantic parse same JSON

Design Decisions

1. No @api_handler decorator for now

The authorize endpoint returns either web.Response or StreamResponse depending on auth type (keypair vs jwt). The @api_handler decorator expects a single return type, so we kept the manual request parsing approach for now.

2. Trafaret handlers preserved

Both trafaret (legacy) and pydantic handlers coexist in auth/__init__.py. The create_app currently routes to the new AuthAPIHandler. As file name confliction happens, I've decided to rm for this commmit, but we can restore and do gradual migration if needed.

3. Test strategy changed

Previous test_handlers.py mocked request.text() to test trafaret's check_params(). With pydantic, validation happens during DTO construction which is already tested in test_dto_compatibility.py. The new test_adapter.py focuses on ActionResult → Response DTO conversion instead.

Test plan

• test_dto_compatibility.py - Gold format tests (trafaret & pydantic parse same JSON)
• test_adapter.py - ActionResult to Response DTO conversion

For decorating authrize with @api_handler,

from @api_handler

 @functools.wraps(handler)
    async def wrapped(first_arg: Any, request: web.Request) -> web.Response:
        kwargs: dict[str, _ParamType] = {}
        for name, param_instance_or_class in signature_parser_map.items():
            param_instance = await _serialize_parameter(request, param_instance_or_class)
            kwargs[name] = param_instance
        response = await handler(first_arg, **kwargs)
        return _parse_response(response)

in _parse_response,

def _parse_response(response: APIResponse) -> web.Response:
    return web.json_response(
        data=response.to_json,
        status=response.status_code,
    )

checks .to_json and status_code attribute, so when 2fa return streamresponse, i think it will be broken.

if i've overlooked on something please let me know!

For open api, unified APIResponse doesn't let open api to refer the response model.
current

@dataclass
class APIResponse:
    _status_code: int
    _data: Optional[BaseResponseModel]

    @classmethod
    def build(cls, status_code: int, response_model: BaseResponseModel) -> Self:
        return cls(_status_code=status_code, _data=response_model)

    @classmethod
    def no_content(cls, status_code: int) -> Self:
        return cls(_status_code=status_code, _data=None)

    @property
    def to_json(self) -> Optional[JSONDict]:
        return self._data.model_dump(mode="json") if self._data else None

    @property
    def status_code(self) -> int:
        return self._status_code

type generic

@dataclass
class APIResponse(Generic[TResponseModel]):
    _data: Optional[TResponseModel]

But it require us to look in every occurences of APIRespone.

For decorating authrize with @api_handler,

checks .to_json and status_code attribute, so when 2fa return streamresponse, i think it will be broken.

if i've overlooked on something please let me know!

Then how about stream_api_handler() instead? This should not be broken

I've been working on @api_streamresponse, and what i've found was action result here,

        result: APIStreamResponse = await handler(first_arg, **kwargs)

@stream_api_handler expects wrapped handler to emit APIStreamResponse and transform it into web.streamResponse.
So usual APIResponse can't be guaranteed to be transformed unlike web.streamResponse <-> web.Response is possible.

• updated to use AliasChoices for two interchangable inputs.

follow up issues:
#8149

• decorator strategy for authorize.

#8150

• Return type clarify for openApi automated builder

Thank you!

Summary

• Migrate auth API handlers from monolithic auth.py to modular package structure
• Add pydantic DTOs for request/response validation
• Preserve legacy handlers in api/legacy/ for regression testing
• Add regression test using both legacy and new handler. let me know if this approach seems valid!

Notes

Deferred items (out of scope)

• current_user vs user_context field doesn't contain what is needed from user_context - kept as-is due to broader impact
• SuccessResponse unification - touches too many files, separate PR
• Circular import workaround: create_app wrapper in __init__.py defers handler.py import
  • Root cause: repositories.session.repository imports api.session.find_dependency_sessions
  • TODO: Move find_dependency_sessions to repository layer to remove wrapper
• OpenAPI addition - refer OpenAPI automation builder for pydantic handlers #8150